home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UDispatcher.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  43.3 KB  |  1,079 lines  |  [TEXT/MPS ]
  1. // UDispatcher.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __UDISPATCHER__
  5. #define __UDISPATCHER__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __GEOMETRY__
  10. #include "Geometry.h"
  11. #endif
  12.  
  13. #ifndef __UAPPLEEVENTS__
  14. #include "UAppleEvents.h"
  15. #endif
  16.  
  17. #ifndef __UBEHAVIOR__
  18. #include "UBehavior.h"
  19. #endif
  20.  
  21. #ifndef __UCOMMANDHANDLER__
  22. #include "UCommandHandler.h"
  23. #endif
  24.  
  25. #ifndef __UGEOMETRY__
  26. #include "UGeometry.h"
  27. #endif
  28.  
  29. #ifndef __ULIST__
  30. #include "UList.h"
  31. #endif
  32.  
  33. #ifndef __ULISTITERATOR__
  34. #include "UListIterator.h"
  35. #endif
  36.  
  37. #ifndef __USCRIPTABLEOBJECT__
  38. #include "UScriptableObject.h"
  39. #endif
  40.  
  41. // CALib
  42.  
  43. #if qContainer
  44.     #ifndef _CALIB_
  45.     #include "CALib.h"
  46.     #endif
  47. #endif
  48.  
  49. // Toolbox
  50.  
  51. #ifndef __BALLOONS__
  52. #include <Balloons.h>
  53. #endif
  54.  
  55. #ifndef __DIALOGS__
  56. #include <Dialogs.h>
  57. #endif
  58.  
  59. //----------------------------------------------------------------------------------------
  60. // Performance monitor menu command constants used by TDispatcher.
  61. //----------------------------------------------------------------------------------------
  62.  
  63. //    const CommandNumber cPerfMonInit = 901;
  64. //    const CommandNumber cPerfMonDump = 902;
  65. //    const CommandNumber cPerfMonToggle = 903;
  66. //    const CommandNumber cPerfMonEnd = 904;
  67.  
  68.  
  69. //----------------------------------------------------------------------------------------
  70. // Debugger menu command constants used by TDispatcher.
  71. //----------------------------------------------------------------------------------------
  72.  
  73. //    const CommandNumber cDebugFlags = 913;
  74. //    const CommandNumber cDoFirstClick = 915;            // <!> Toggle. "'Do First Click' for this
  75. //    const CommandNumber cRefreshFrontWindow = 917;        // <!> Action. "Refresh Front Window"
  76. //    const CommandNumber cSetSysJust = 921;                // <!> Action. "Switch system
  77.                                                     // justification"
  78.  
  79. //----------------------------------------------------------------------------------------
  80. // Arguments of TDispatcher::GetActiveWindow
  81. //----------------------------------------------------------------------------------------
  82. const Boolean kFloatersOK = TRUE;
  83. const Boolean kNoFloaters = FALSE;
  84.  
  85. //----------------------------------------------------------------------------------------
  86. // Timeout Argument of TDispatcher::InteractWithUser
  87. //----------------------------------------------------------------------------------------
  88.  
  89. const long kMacAppTimeout = 901;    // let MacApp decide how to handle the timeout
  90.  
  91. //----------------------------------------------------------------------------------------
  92. // Forward and external class declarations. 
  93. //----------------------------------------------------------------------------------------
  94.  
  95. //    struct StandardFileReply;
  96. class TDocument;
  97. #if qContainer
  98. class TFileBasedDocument;
  99. #endif
  100. class TEvent;
  101. class TDispatcher;
  102. class TFile;
  103. class TMenuBarManager;
  104. class TToolboxEvent;
  105. class TTracker;
  106. class TView;
  107. class TWindow;
  108.  
  109.  
  110. //----------------------------------------------------------------------------------------
  111. // CDocumentIterator
  112. //----------------------------------------------------------------------------------------
  113.  
  114. class CDocumentIterator : public CObjectIterator
  115. {
  116. public:
  117.     CDocumentIterator(const TDispatcher* itsApplication,
  118.                       ArrayIndex itsLowBound, ArrayIndex itsHighBound,
  119.                       Boolean itsForward);
  120.  
  121.     CDocumentIterator(const TDispatcher* itsApplication, Boolean itsForward);
  122.  
  123.     CDocumentIterator(const TDispatcher* itsApplication);
  124.     
  125.     virtual ~CDocumentIterator();
  126.     
  127.     inline TDocument* CurrentDocument()
  128.     { return (TDocument *)this->CurrentObject(); }
  129.         // returns the current document
  130.     
  131.     inline TDocument* FirstDocument()
  132.     { return (TDocument *)this->FirstObject(); }
  133.         // return the first document in the iteration
  134.  
  135.     inline TDocument* NextDocument()
  136.     { return (TDocument *)this->NextObject(); }
  137.         // advances the iteration and then returns the document
  138. };
  139.  
  140. //----------------------------------------------------------------------------------------
  141. // CNoGhostDocsIterator
  142. //----------------------------------------------------------------------------------------
  143.  
  144. class CNoGhostDocsIterator : public CDocumentIterator
  145. {
  146. public:
  147.     inline CNoGhostDocsIterator(const TDispatcher* itsApplication,
  148.                       ArrayIndex itsLowBound, ArrayIndex itsHighBound,
  149.                       Boolean itsForward) :
  150.     CDocumentIterator(itsApplication, itsLowBound, itsHighBound, itsForward)
  151.     { }
  152.  
  153.     inline CNoGhostDocsIterator(const TDispatcher* itsApplication, Boolean itsForward) :
  154.     CDocumentIterator(itsApplication, itsForward)
  155.     { }
  156.  
  157.     inline CNoGhostDocsIterator(const TDispatcher* itsApplication) :
  158.     CDocumentIterator(itsApplication)
  159.     { }
  160.     
  161.     virtual ~CNoGhostDocsIterator();
  162.     
  163.     virtual Boolean More();
  164. };
  165.  
  166. #if qContainer
  167.  
  168. //----------------------------------------------------------------------------------------
  169. // CCADocumentIterator -- iterate over container documents
  170. //----------------------------------------------------------------------------------------
  171.  
  172. class CCADocumentIterator : public CObjectIterator
  173. {
  174. public:
  175.     CCADocumentIterator(const TDispatcher* itsApplication,
  176.                       ArrayIndex itsLowBound, ArrayIndex itsHighBound,
  177.                       Boolean itsForward);
  178.  
  179.     CCADocumentIterator(const TDispatcher* itsApplication, Boolean itsForward);
  180.  
  181.     CCADocumentIterator(const TDispatcher* itsApplication);
  182.     
  183.     virtual ~CCADocumentIterator();
  184.     
  185.     inline TFileBasedDocument* CurrentDocument()
  186.     { return (TFileBasedDocument *)this->CurrentObject(); }
  187.     
  188.     inline TFileBasedDocument* FirstDocument()
  189.     { return (TFileBasedDocument *)this->FirstObject(); }
  190.  
  191.     inline TFileBasedDocument* NextDocument()
  192.     { return (TFileBasedDocument *)this->NextObject(); }
  193. };
  194.  
  195. #endif
  196. //----------------------------------------------------------------------------------------
  197. //  TEventList: A list for keeping TEvents ordered by priority
  198. //----------------------------------------------------------------------------------------
  199.  
  200. class TEventList : public TSortedList
  201. {
  202.     MA_DECLARE_CLASS;
  203.     
  204. public:
  205.     TEventList();
  206.         // Empty constructor to satisfy compiler.
  207.     virtual ~TEventList();
  208.         // Destructor
  209.  
  210.     void IEventList();
  211.         // Initialize the EventList procedurally.
  212.  
  213.     virtual CompareResult Compare(TObject* item1,
  214.                                  TObject* item2);
  215.         // Compares Two TEvents based on their priority
  216.  
  217.     virtual void Insert(TObject* item);
  218.         // Overridden to guarantee insertion even in low memory and to preserve arrival
  219.         // sequence within "Compare" ordering.
  220.  
  221. };
  222.  
  223. //----------------------------------------------------------------------------------------
  224. // TDispatcher: The purpose of this class is to implement the main event loop that all
  225. // Macintosh applications must have. There is only one instance of TDispatcher. One thing
  226. // that TDispatcher does is to interpret the raw events that are posted and convert them
  227. // into higher-level events. For example, it converts a click in the menu bar into a 'menu
  228. // event' that contains the menu ID/ item number that was chosen by the user.
  229. //----------------------------------------------------------------------------------------
  230.  
  231. class TDispatcher : public TCommandHandler, public MDefaultScriptableObject
  232. {
  233.     MA_DECLARE_CLASS;
  234.     
  235. public:
  236.     OSType fCreator;                            // The application signature; Creator type
  237.                                                 // for files.  This is used by DoMakeFile.
  238.                                                 
  239.     OSType fMainFileType;                        // principal file type opened/printed by
  240.                                                 // application; by default,
  241.                                                 // TDispatcher::SFGetFilters returns a
  242.                                                 // list of just this. Used by DoMakeFile
  243.  
  244.     TEventList* fEventList;                        // Events/Commands that were posted for
  245.                                                 // execution
  246.                                                 
  247.     
  248. //    Boolean fLaunchWithNewDocument;                // True (the default) to create a new
  249.                                                 // untitled document when the application
  250.                                                 // is launched without a document.
  251.                                                 
  252.     Boolean fAllowApplicationToSleep;            // Whether the application should be
  253.                                                 // allowed to "sleep" and thus share
  254.                                                 // processor time, when getting events
  255.  
  256.     ProcessSerialNumber fProcessNumber;            // This application's process serial
  257.                                                 // number.
  258.  
  259.     IdlePhase fIdlePhase;                        // The current idle phase
  260.  
  261.     Boolean fAlwaysTrackCursor;                    // set this to true when you want the
  262.                                                 // application to track the cursor even if
  263.                                                 // it doesn't stray outside gCursorRgn.
  264.                                                 
  265.     Boolean fDone;                                // set this to true when you want the
  266.                                                 // application to terminate
  267.  
  268.     short fClickCount;                            // number of 'saved up' mouse clicks. If a
  269.                                                 // mouseDown, the value is that returned
  270.                                                 // by the call to
  271.                                                 // TDispatcher::CountClicks. If a mouseUp,
  272.                                                 // the value is left alone. Otherwise, set
  273.                                                 // to 0. Also set to 0 is the 2 clicks
  274.                                                 // were in different parts ofthe window.
  275.                                                 
  276.     short fLastClickPart;                        // the list window part clicked in-used
  277.                                                 // for double click detection
  278.                                                 
  279.     CPoint fLastMousePoint;                        // coordinates of mouse in last event
  280.                                                 // passed to TDispatcher.CountClicks
  281.                                                 
  282.     long fLastUpTime;                            // time of last mouse up event
  283.  
  284.     long fNextSpaceMessage;                        // time when next low space message should
  285.                                                 // be displayed
  286.                                                 
  287.     long fLowSpaceInterval;                        // If >= 0, the frequency (in Ticks) with
  288.                                                 // which MacApp displays a low space
  289.                                                 // alert. (Defaults to kLowSpaceInterval.)
  290.                                                 // If < 0, MacApp doesn't display an
  291.                                                 // alert.
  292.                                                 
  293.     short fMainEventMask;                        // Event mask used in main event loop.
  294.                                                 // Initialized by InitUMacApp.
  295.                                                 
  296.     Boolean fSysWindowActive;                    // True if the front window is a system
  297.                                                 // window
  298.     
  299.     //    Boolean fUndoState;                            // are we in undo or redo
  300.     
  301.     CommandNumber fUndoCommand;                    // the command number currently in the undo menu
  302.     
  303.     CommandNumber fRedoCommand;                    // the command number currently in the redo menu
  304.     
  305.     TList* fDocumentList;                        // list of documents
  306.  
  307.     TList* fFreeWindowList;                        // list of free-standing (documentless)
  308.                                                 // windows
  309.     
  310.     TEventHandler* fHeadCohandler;                // head of linked list of global
  311.                                                 // co-handlers
  312.  
  313.     TEventHandler* fTarget;                        // the TEventHandler that gets the first
  314.                                                 // chance at DoCommand, DoSetupMenu,
  315.                                                 // DoKeyEvent, Idle; should never be NULL
  316.                                                 // -- If you do not want your own target
  317.                                                 // set this to the application object
  318.                                                 
  319.     short fEventLevel;                            // A count of the number of nested calls
  320.                                                 // to PollToolboxEvent.
  321.                                                 
  322.     ResNumber fDisplayedMenus;                    // menus that are read in and installed in
  323.                                                 // menu bar
  324.                                                 
  325.     ResNumber fMBarHierarchical;                // menus that pop up when a menu item is
  326.                                                 // choosen
  327.     
  328.     ResNumber fOtherMenus;                        // menus that are read in but not
  329.                                                 // installed
  330.     
  331.     RgnHandle fSleepRegion;                        // the region that will be passed to
  332.                                                 // WaitNextEvent as the sleep region.
  333.                                                 // Computed from the cursor and help
  334.                                                 // regions
  335.                                                 
  336.     RgnHandle fCursorRegion;                    // the current cursor region
  337.     
  338.     RgnHandle fHelpRegion;                        // the current help region
  339.  
  340.     Boolean fWantKeyUpEvents;                    // set this to true in your constructor to set
  341.                                                 // the system mask to allow key-up events
  342.  
  343. //    #if qDebug
  344. //        TWindow* fDebugFlagsWindow;                    // Window for setting the debug flags
  345. //    #endif
  346.  
  347.     //------------------------------------------------------------------------------------
  348.     // Initialization and Free
  349.     //------------------------------------------------------------------------------------
  350.  
  351.     TDispatcher();
  352.         // Constructor
  353.     virtual ~TDispatcher();
  354.         // Destructor
  355.  
  356.     void IDispatcher(OSType itsMainFileType,
  357.                                      OSType itsCreator);
  358.         // itsMainFileType should be the 4-byte file type that this application reads and
  359.         // writes.  itsCreator is the application's signiture.  They are used when creating
  360.         // a default file with DoMakeFile and to display the proper file types in the
  361.         // StandardFile dialogs.
  362.         
  363. //    virtual Boolean ChooseApplication(AEAddressDesc& theAddress);
  364.         // Choose a running application using the PPCBrowser and store the address in an
  365.         // AppleEvent address
  366.  
  367.     virtual TMenuBarManager* MakeMenuBarManager();
  368.         // Creates an instance of TMenuBarManager
  369.     
  370.     //------------------------------------------------------------------------------------
  371.     // Event Handling
  372.     //------------------------------------------------------------------------------------
  373.  
  374.     virtual TToolboxEvent* GetEvent(short eventMask, long sleep, 
  375.                                             RgnHandle sleepRegion);
  376.         // Calls WaitNextEvent (or GetNextEvent) with the given event mask, sleep, and
  377.         // sleep region parameters. You can override this if you have an alternate source
  378.         // for events.
  379.  
  380.     virtual void HandleAlienEvent(TToolboxEvent* event);
  381.         // This method is called upon to deal with 'application-specific' events
  382.  
  383.     virtual void MainEventLoop();
  384.         // Loop on PollEvent until the application is done
  385.  
  386.     virtual void DispatchEvent(TToolboxEvent* event);
  387.  
  388.     virtual void DoToolboxEvent(TToolboxEvent* event);
  389.         // When this is called by MacApp, theEvent is the event to be processed.
  390.  
  391.     virtual void DidEvent(TToolboxEvent* event);
  392.  
  393.     // Added for 3.5
  394.     virtual void DispatchMenuEvent(TToolboxEvent* event, long menuItem);
  395.         // Handles menu events. 
  396.  
  397.     virtual void HandleActivateEvent(TToolboxEvent* event);
  398.         // Handles activate (and deactivate) events. Calls the window's Activate method,
  399.         // and invalidates the menubar if activating the window.
  400.  
  401.     virtual void HandleDiskEvent(TToolboxEvent* event);
  402.         // Handles disk events. Calls DIBadMount if the high word of theEvent's message is
  403.         // <> noErr
  404.  
  405.     virtual void HandleHighLevelEvent(TToolboxEvent* event);
  406.         // Process a high level event. Default behavior is to assume it is an AppleEvent.
  407.  
  408.     virtual void KeyEventToComponents(TToolboxEvent* event);
  409.         // re-extracts components of an event in a script manager compatible way.
  410.  
  411.     virtual void HandleKeyDownEvent(TToolboxEvent* event);
  412.         // Handles key down events. If the command key is down, then this calls
  413.         // CommandKey. Otherwise it calls fTarget->DoKeyEvent.
  414.  
  415.     virtual void HandleKeyUpEvent(TToolboxEvent* event);
  416.         // Handles key up events. Calls fTarget->DoKeyEvent.
  417.  
  418.     virtual void HandleMouseDown(TToolboxEvent* event);
  419.         // Called when a mouse down occurs; this cases on whereMouseDown and does the
  420.         // right thing.
  421.  
  422.     virtual TTracker* TrackMouse(const VPoint& theMouse, CPoint hysteresis,
  423.                                         TTracker* theCommand);
  424.         // Responsible for mouse tracking. !!! Candidate for eventhandler method?
  425.  
  426.     virtual void HandleMouseUp(TToolboxEvent* event);
  427.         // Sets fLastUpTime.
  428.  
  429.     virtual void HandleSystemEvent(TToolboxEvent* event);
  430.         // Handles "system" events, in particular suspend/ resume events and mouse moved
  431.         // events. Calls RegainControl if switching in, AboutToLoseControl if switching
  432.         // out, or TrackCursor if it is a mouse-moved event.
  433.  
  434.     virtual void HandleToolboxEvent(TToolboxEvent* event);
  435.         // Handles the dispatching of DoToolboxEvent messages between itself and Behaviors.
  436.  
  437.     virtual void HandleUpdateEvent(TToolboxEvent* event);
  438.         // Handles window update events. Calls UpdateEvent for the window indicate by the
  439.         // event.
  440.  
  441.     Boolean IsFrontProcess();
  442.         // Returns true if the application is currently the front process.
  443.  
  444.     virtual void MakeFrontProcess();
  445.         // Makes this application the front process.
  446.         
  447.     virtual void WakeProcess();
  448.         // Wakes this process if it is sleeping in WaitNextEvent. Used by callback
  449.         // procs (drag manager, apple event manager) that get called when the
  450.         // process is in a WaitNextEvent, to return from WNE and reevaluate the
  451.         // internal command que.
  452.  
  453.     virtual void OpenDeskAccessory(const CStr255& deskAccName);
  454.         // Attempts to open the desk accessory whose name is deskAccName. Called from
  455.         // TDispatcher::MenuEvent when an Apple menu item is chosen, and the item has a
  456.         // negative command number.
  457.  
  458.     virtual void PollEvent(Boolean allowApplicationToSleep);
  459.         // Polls for events/commands and processes them.
  460.  
  461.     virtual Boolean PollToolboxEvent(Boolean allowApplicationToSleep);
  462.         // Polls for events calling Idle before waitNextEvent if there are no events
  463.         // pending and the application is allowed to go to sleep
  464.         // (kAllowApplicationToSleep), calls HandleEvent with the event, if there is one.
  465.         // and then idles if necessary.
  466.  
  467.     void Run();
  468.         // call MainEventLoop
  469.  
  470.     virtual void UpdateAllWindows();
  471.         // Process all update events in the queue.
  472.  
  473.     virtual Boolean InModalState();
  474.         // Returns true if the front window is modal.
  475.  
  476.     short GetMainEventMask();
  477.         // Retrieve the current main event mask.
  478.         
  479.     short SetMainEventMask(short newMask);
  480.         // Set the main event mask and return the old one.
  481.  
  482.     //------------------------------------------------------------------------------------
  483.     // Target and Cohandlers
  484.     //------------------------------------------------------------------------------------
  485.  
  486.     virtual void InstallCohandler(TEventHandler* aCohandler,
  487.                                          Boolean addIt);
  488.         // Used to add (addIt = true) or delete (addIt = false) a cohandler to/ from the
  489.         // global list of cohandlers
  490.  
  491.     virtual TWindow* GetFrontWindow();
  492.         // Returns the window object reference for the frontmost application window
  493.         // (whether active or not). 
  494.         // Returns NULL if the FrontWindow window is not a window object.
  495.  
  496.     virtual TWindow* GetActiveWindow(Boolean floatersAreOkay);
  497.         // Returns the window object reference for the active application window.
  498.         // Returns NULL if the FrontWindow window is not a window object.
  499.  
  500.     void SetTarget(TEventHandler* newTarget);
  501.         // Sets the current target (the head of the target chain) for the application.
  502.  
  503.     TEventHandler* GetTarget();
  504.         // Returns the current target
  505.  
  506.  
  507.     //------------------------------------------------------------------------------------
  508.     // Finder Requests
  509.     //------------------------------------------------------------------------------------
  510.  
  511. //        virtual Boolean CanOpenDocument(CommandNumber itsCommandNumber, TFile* aFile);
  512.             // Simulates the filtering done by Std File; this is only called when opening/
  513.             // printing documents from the finder; when using Std File, Std File does the
  514.             // filtering.
  515.  
  516. //        virtual void HandleFinderRequest();
  517.             // If the AppleEvents Manager is not required or present: Gets the info from the
  518.             // finder about what files to open/ print and opens/ prints them.
  519.     
  520.  
  521.     //------------------------------------------------------------------------------------
  522.     // Opening and Printing Documents
  523.     //------------------------------------------------------------------------------------
  524.  
  525.     virtual TDocument* FindDocument(TFile* aFile);
  526.         // Given a TFile, if that document is already opened, returns the TDocument.
  527.         // Otherwise returns NULL.
  528.  
  529. //        virtual Boolean ChooseDocument(CommandNumber itsCommandNumber, TList** aFileList);
  530.             // Call this to make a Std File Get call; returns true is user selected a file.
  531.  
  532. //        virtual TDocument* DoMakeDocument(CommandNumber itsCommandNumber, TFile* itsFile);
  533.             // Must be overridden. Based on itsCommandNumber create a document object of the
  534.             // appropriate kind. If itsFile <> NULL it is attached to the document
  535.  
  536.     virtual TFile* DoMakeFile(CommandNumber itsCommandNumber);
  537.         // Default behavior is to return an instance of TFile. May be overridden to create
  538.         // a file of your own special type.
  539.  
  540. //        virtual CommandNumber KindOfDocument(CommandNumber itsCommandNumber, TFile* itsFile);
  541.             // Given a command number and a specification of the file, return the command number to
  542.             // pass to DoMakeDocument that indicates the type of document to make; Default is
  543.             // to return itsCommandNumber. If you have multiple document types, a good convention
  544.             // is to return the command numbers assigned to create new documents of each kind.
  545.             // aFile will be NULL if we are creating a brand new document, rather than opening
  546.             // an existing document.
  547.  
  548. //        virtual TDocument* OpenNew(CommandNumber itsCommandNumber);
  549.             // Called when the application is opened (itsCommandNumber = cFinderNew), or when NEW
  550.             // is chosen from menu (itsCommandNumber = cNew). If you do not want to create a new
  551.             // document when the user opens the application, override this and do nothing if
  552.             // itsCommandNumber = cFinderNew. Returns the document that was opened. 
  553.  
  554. //        virtual TDocument* OpenOld(CommandNumber itsOpenCommand, TList* aFileList);
  555.             // Called when opening an existing document from finder (itsCommandNumber =
  556.             // cFinderOpen) or if OPEN is chosen from menu (itsCommandNumber = cOpen).
  557.             // It can also handle stationery.
  558.  
  559. //        virtual void PrintDocuments(CommandNumber itsCommandNumber, TList* aFileList);
  560.             // Called to print the documents specified from the finder.  The list of files may
  561.             // have come from a 'pdoc' AppleEvent or from HandleFinderRequest
  562.  
  563. //        virtual void GetStandardFileParameters(CommandNumber itsCommandNumber,
  564. //                                               ProcPtr& fileFilter,
  565. //                                               TypeListHandle& typeList,
  566. //                                               short& dlgID,
  567. //                                               CPoint& where,
  568. //                                               ProcPtr& dlgHook,
  569. //                                               ProcPtr& modalFilter,
  570. //                                               Ptr& activeList,
  571. //                                               ProcPtr& activateProc,
  572. //                                               StandardFileReply* reply,
  573. //                                               void*& yourDataPtr);
  574.             // Called to return all the parameters that should be passed to SFPGetFile or
  575.             // CustomGetFile, and CanOpenDocument; Defaults to:
  576.             //         dlgID = getDlgID or sfGetDialogID;
  577.             //         where = (100, 100) or (-1, -1);
  578.             //         fileFilter = NULL;
  579.             //         dlgHook = NULL;
  580.             //         modalFilter = gStandardFileFilter;
  581.             //         activeList := NULL;
  582.             //         activateProc := NULL;
  583.             //         yourDataPtr := NULL;
  584.  
  585. //        virtual void GetFileTypeList(CommandNumber itsCommandNumber,
  586. //                                            TypeListHandle& typeList);
  587.             // Return an valid handle to a list of file types supported by your application.
  588.             // and the number of types in the list. The default is to allocate enough space
  589.             // for fMainFileType.  Called by ChooseDocument to determine the types of files
  590.             // to display.  If no type is specified then all types are displayed.
  591.  
  592.  
  593.     //------------------------------------------------------------------------------------
  594.     // Termination
  595.     //------------------------------------------------------------------------------------
  596.  
  597.     virtual void Close();
  598.         // Called when the user chooses Quit from the menu, and tries to save all the open
  599.         // documents. If all succeed the application terminates. Signals Failure with
  600.         // error = noErr and message = messageCancelled if user cancels
  601.  
  602.  
  603.     //------------------------------------------------------------------------------------
  604.     // Hierarchy
  605.     //------------------------------------------------------------------------------------
  606.  
  607.     virtual void AddDocument(TDocument* aNewDocument);
  608.         // Add another document to my list of documents, and make it the current one
  609.  
  610.     virtual void AddWindow(TWindow* aWindow);
  611.         // Add the window to the free-window list
  612.  
  613.     virtual void DeleteDocument(TDocument* docToDelete);
  614.         // Delete a document from my list of documents
  615.  
  616.     virtual void DeleteWindow(TWindow* windowToDelete);
  617.         // Delete a window from my list of free windows
  618.  
  619.  
  620.     //------------------------------------------------------------------------------------
  621.     // Window Manager Windows
  622.     //------------------------------------------------------------------------------------
  623.     
  624.     // Removed for 3.5
  625.     //    virtual void SelectToolboxWindow(WindowRef windowToSelect);
  626.     //        // "Selects" windowToSelect by calling the toolbox routine SelectWindow. When any
  627.     //        // window is selected, it goes through here. We never call SelectWindow directly.
  628.  
  629.     virtual WindowRef NewToolboxWindow(Ptr storage, short rsrcId,
  630.                                            Boolean& isResizable,
  631.                                            Boolean& isClosable);
  632.         // Get a Window Manger window resource whose resource id is rsrId. Return
  633.         // isResizable and isClosable based upon the 'WIND' resource.
  634.  
  635.     virtual TWindow* WMgrToWindow(WindowRef aWMgrWindow);
  636.         // Returns the window object that represents the given Window Manager window, or
  637.         // NULL if there is no window object.
  638.     
  639.  
  640.     //------------------------------------------------------------------------------------
  641.     // Idle Events
  642.     //------------------------------------------------------------------------------------
  643.     
  644.     virtual long GetWaitTicks(Boolean allowApplicationToSleep);
  645.         // Compute the "wait ticks" to be passed to GetEvent
  646.  
  647.     virtual void Idle(IdlePhase phase);
  648.         // Parcels out idle time to the DoIdle method in the target and cohandler chains
  649.         // of TEvtHandlers. If your application needs to do something at idle time then
  650.         // override DoIdle instead of this method.
  651.  
  652.  
  653.     //------------------------------------------------------------------------------------
  654.     // Cursor and Help
  655.     //------------------------------------------------------------------------------------
  656.     
  657.     virtual RgnHandle GetSleepRegion();
  658.         // Return the "sleep region" to be passed to GetEvent
  659.  
  660.     virtual void GetDefaultCursorRegion(CPoint globalMouse, RgnHandle cursorRegion);
  661.         // Computes the cursor region for the case where no window has claimed the cursor
  662.  
  663.     virtual void InstallHelpMenuItems();
  664.         // Override this method to install your help menu item(s).  Use
  665.         // gMenuBarManager->AddHelpMenuItem( "^0 Help", kYourHelpCommandNumber );
  666.         
  667.     virtual void GetDefaultHelpRegion(CPoint globalMouse,  RgnHandle helpRegion);
  668.         // Computes the help region for the case where no window has claimed the cursor
  669.  
  670.     virtual void GetHelpParameters(ResNumber helpResource,
  671.                                     short helpIndex,
  672.                                     short helpState,
  673.                                     HMMessageRecord& helpMessage,
  674.                                     CPoint& localQDTip,
  675.                                     CRect& localQDRect,
  676.                                     short& balloonVariant);
  677.         // Gets balloon contents from an 'hdlg' resource. Called by TView::GetHelpParameters
  678.  
  679.     virtual void DoSetCursor(CPoint globalMouse, RgnHandle cursorRegion);
  680.         // Sets the cursor to an arrow and computes the region for which it is claimed.
  681.         // Called when no view has set the cursor
  682.  
  683.     virtual void TrackCursor(CPoint globalMouse);
  684.         // Allows windows/views to set the cursor and cursor region via TView::HandleCursor
  685.         // and TView::DoSetCursor. If no region is set, the cursor is set to an arrow and
  686.         // the largest possible default cursor region is calculated.
  687.  
  688.     virtual void HandleCursor(CPoint globalMouse, RgnHandle cursorRegion);
  689.  
  690.     virtual void DoShowHelp(CPoint globalMouse, RgnHandle helpRegion);
  691.         // !!!
  692.  
  693.     virtual void TrackHelp(CPoint globalMouse);
  694.         // !!!
  695.  
  696.     virtual void HandleHelp(CPoint globalMouse, RgnHandle helpRegion);
  697.  
  698.     void InvalidateMouseRegions();
  699.         // Invalidates the cursor and help regions
  700.  
  701.     void InvalidateCursorRgn();
  702.         // Sets the cursor region to the empty region
  703.  
  704.     void InvalidateHelpRgn();
  705.         // Sets the help region to the empty region
  706.  
  707.     virtual Boolean IsCursorRgnInvalid();
  708.         // Returns true if the cursor region needs to be recalculated
  709.  
  710.     virtual Boolean IsHelpRgnInvalid();
  711.         // Returns true if the help region needs to be recalculated
  712.     
  713.  
  714.     //------------------------------------------------------------------------------------
  715.     // Keyboard events
  716.     //------------------------------------------------------------------------------------
  717.     
  718.     virtual void DoKeyEvent(TToolboxEvent* event);
  719.         // Handle keydown events.
  720.  
  721.  
  722.     //------------------------------------------------------------------------------------
  723.     // Menu Events
  724.     //------------------------------------------------------------------------------------
  725.     
  726.     virtual void DoCommandKeyEvent(TToolboxEvent* event);
  727.         // Called when a keyDown event is received and the command key is down.
  728.  
  729.     virtual void MenuEvent(long menuItem);
  730.         // Given a value returned by MenuKey or MenuSelect, figure out the command number
  731.         // that was chosen, have the application create a command object, and post it.
  732.  
  733.     virtual void SetupUndoRedoMenus();
  734.         // Setup the Undo and Redo menu items. 
  735.     
  736.     virtual void SetUndoText(CommandNumber id);
  737.         // Called to setup the Undo menu item. 
  738.  
  739.     virtual void SetRedoText(CommandNumber id);
  740.         // Called to setup the Redo menu item. 
  741.  
  742.     virtual void SetupTheMenus();
  743.         // Initiates the process of enabling & checking menu items.
  744.  
  745.     //------------------------------------------------------------------------------------
  746.     // Opening and Closing Windows
  747.     //------------------------------------------------------------------------------------
  748.     
  749.     virtual void CloseToolboxWindow(WindowRef aWMgrWindow);
  750.         // Called when user closes a window either with a menu item or with a GoAway box.
  751.         // Returns FALSE if user cancels. 
  752.         // (Used to signal Failure with error = noErr and message = messageCancelled if user cancels)
  753.  
  754.  
  755.     //------------------------------------------------------------------------------------
  756.     // Command Management
  757.     //------------------------------------------------------------------------------------
  758.     
  759.     virtual TEvent* RetrieveAnEvent(); // override
  760.         // Retrieves a previously posted event/ command from the queue. NULL if there are no
  761.         // queued commands.
  762.  
  763.     void RemoveEvent(TEvent* event);
  764.         // Removes a previously posted event/ command from the queue. There is no error
  765.         // if the event is not in the queue. 
  766.  
  767.     virtual void ProcessEvent(TEvent* event);
  768.         // Processes the given event from the queue of event objects. The event may be a
  769.         // Toolbox event or a command object. This method calls the event's Process method.
  770.  
  771.     virtual void PostAnEvent(TEvent* event); // override
  772.         // Called to post an event or command to a queue for later processing. Default is
  773.         // to hand off to fNextHandler
  774.  
  775.     virtual void PostCommand(TCommand* command); // override
  776.         // Called to post a command to the queue for later execution.
  777.  
  778.     //------------------------------------------------------------------------------------
  779.     // Double/Triple Clicks
  780.     //------------------------------------------------------------------------------------
  781.     
  782.     virtual short CountClicks(TToolboxEvent* event, short whereMouseDown);
  783.         // Called by TDispatcher::HandleMouseDown. Returns the number of clicks that can
  784.         // be considered multiple clicks (e.g. if it returns 1 the mouse down should be
  785.         // treated as a single click, or possibly the first click of a multi-click
  786.         // sequence. If it returns 2 the click should be considered a double-click, etc. A
  787.         // click is considered part of a multi-click sequence if the mouse down was within
  788.         // the proper time range of the previous mouse up, and was within the proper
  789.         // number of pixels of the last mouse down. TDispatcher::HandleMouseDown sets
  790.         // theClickCount of its EventInfo record to the result of this function.
  791.         // aPDownEvent is a pointer to the mouse down event. whereMouseDown is the result
  792.         // of FindWindow on the event.
  793.  
  794.     //------------------------------------------------------------------------------------
  795.     // Clipboard support
  796.     //------------------------------------------------------------------------------------
  797.     
  798.     virtual void DoLaunchClipboard();
  799.         // calls gClipboardMgr->Launch
  800.  
  801.     virtual TView* MakeViewForAlienClipboard();
  802.         // Override this to create a view to handle your application's specific data
  803.         // types. Return NULL (the default) to have the clipboard manager create a default
  804.         // view.
  805.  
  806.  
  807.     //------------------------------------------------------------------------------------
  808.     // Command Handlers
  809.     //------------------------------------------------------------------------------------
  810.     
  811.     virtual void DoMenuCommand(CommandNumber aCommandNumber);
  812.         // Handles the application specific menu commands.
  813.  
  814.     virtual void DoSetupMenus();
  815.  
  816.     virtual void AboutToLoseControl(Boolean convertClipboard);
  817.         // Called when about to activate a Desk Accessory, switch out to another
  818.         // application, or Terminate. convertClipboard is generally true, except it will
  819.         // be false if we get a System event that does not require Clipboard conversion
  820.  
  821.     virtual void RegainControl(Boolean checkClipboard);
  822.         // Called when switching in or when leaving a desk accessory
  823.  
  824. //    virtual void DoNew(CommandNumber theCmdNumber);
  825.     // Handles the New menu item.
  826.  
  827. //    virtual void DoOpen(CommandNumber theCmdNumber);
  828.     // Handles the Open menu item.
  829.  
  830.     //------------------------------------------------------------------------------------
  831.     // Error Alerts
  832.     //------------------------------------------------------------------------------------
  833.  
  834.     virtual void Beep(short duration);
  835.         // Call this method when you want to beep at the user. Sound manager users may
  836.         // have to override this method to integrate its functionality in with your
  837.         // application
  838.  
  839.     virtual void ShowError(OSErr error, long message);
  840.         // Calls ErrorAlert to display an error alert.
  841.  
  842.     virtual void SpaceIsLowAlert();
  843.         // Called when space is low, at intervals of kLowSpaceInterval ticks. Displays an
  844.         // alerting informing the user that memory space is low. Override this if you wish
  845.         // to take more appropriate action.
  846.  
  847.     //------------------------------------------------------------------------------------
  848.     // AppleEvent Handling
  849.     //------------------------------------------------------------------------------------
  850.  
  851.     virtual Boolean DoUndoRedo(TCommandHandler* theContext,
  852.                                CommandNumber aCommandNumber,
  853.                                MScriptableObject* theTarget);
  854.     // Handles the undo choice from the menu. If you want undo/redo to be recordable
  855.     // your DoMenuCommand method should call this on cUndo.
  856.  
  857.     virtual Boolean UndoRedoInContext(TCommandHandler* theContext,
  858.                                       CommandNumber aCommandNumber);
  859.     // Handles the undo event. TDispatcher will handle this for itself, but if
  860.     // you handle undo/redo in another context you should call this from that object's
  861.     // DoScriptCommand method.
  862.  
  863. //        virtual void DoAEClose(TAppleEvent* message,
  864. //                               TAppleEvent* reply);
  865.         // Handles the close event for the application.
  866.  
  867. #if qAttachable
  868.     virtual Boolean HandleOSAEvent(CommandNumber aCommandNumber,
  869.                                     TAppleEvent* message,
  870.                                     TAppleEvent* reply);
  871.     // Overridden to not give OSA the run AppleEvent.
  872. #endif
  873.  
  874.     virtual void DoScriptCommand(CommandNumber aCommandNumber,
  875.                                 TAppleEvent* message,
  876.                                 TAppleEvent* reply);
  877.     // Handles object model AppleEvents for the application.
  878.  
  879. //        virtual void DoAECreateElement(TAppleEvent* message,
  880. //                                       TAppleEvent* reply);
  881.         // Creates a new document. If your application has more than one type of document
  882.         // you'll need to override this method. The default simulates choosing "New" from
  883.         // the file menu.
  884.  
  885.     virtual long CountContainedObjects(DescType desiredType);
  886.     // Counts contained documents and window.
  887.  
  888.     virtual MScriptableObject* GetContainedObject(DescType desiredType,
  889.                                               DescType selectionForm,
  890.                                               const CAEDesc& selectionData);
  891.  
  892.     virtual MScriptableObject* GetIndContainedObject(DescType desiredType,
  893.                                                      long index);
  894.     // Returns a contained document or window.
  895.  
  896.     virtual TWindow* GetWindowByIndex(short wIndex);
  897.     // Returns a window by front to back order.
  898.     
  899.     virtual TWindow* GetPaletteByIndex(short index);
  900.     // Returns a palette by front to back order.
  901.  
  902.     virtual TDocument* GetDocumentByIndex(DescType desiredType,
  903.                                           short wIndex);
  904.     // Returns a document based on its position in the application's fDocumentList.
  905.  
  906.     //------------------------------------------------------------------------------------
  907.     // Scripting Utilities
  908.     //------------------------------------------------------------------------------------
  909.  
  910.  
  911.     virtual Boolean MakeObjectSpecifier(CAEDesc& theObjectSpecifier,
  912.                                      DescType preferredForm = formName);
  913.     // Creates an object specifier for the application.
  914.  
  915.     virtual Boolean IsDocumentClass(DescType desiredType);
  916.     // If your application supports more than one document class you should override this.
  917.     // This method is then called in place of using (desiredType == cDocument).
  918.  
  919.     virtual void ReportReplyError(CommandNumber fromCmdNum,
  920.                                   OSErr theError,
  921.                                   const CStr255& theErrStr);
  922.     // When a reply returned through a TSendAECommand contains an error it is sent
  923.     // through this method for reporting.
  924.  
  925.     //------------------------------------------------------------------------------------
  926.     // Dispatcher Properties
  927.     //------------------------------------------------------------------------------------
  928.  
  929.     virtual void SetObjectProperty(const CAEDesc& thePropertyValue,
  930.                                    DescType whichProperty);
  931.     // Sets application properties.
  932.  
  933.     virtual Boolean GetObjectProperty(CAEDesc& thePropertyValue,
  934.                                       DescType whichProperty,
  935.                                       const CAEDesc& desiredType);
  936.     // Gets application properties.
  937.  
  938.     //------------------------------------------------------------------------------------
  939.     // Miscellaneous
  940.     //------------------------------------------------------------------------------------
  941.  
  942.     virtual void DoMakeDependencySpace();
  943.         // Creates a dependency space for storing dependencies, and stores it in gMacAppDependencies.
  944.         
  945. //    virtual void DoAboutBox();
  946.         // Called to show the "About the App" information
  947.  
  948.     virtual void InvalidateFocus();
  949.         // Called to indicate that a view is unfocused when you don't know which view was focused.
  950.  
  951.     virtual Boolean IsHelpEnabled();
  952.         // Returns true if the Help Manager is present and the user has enabled help
  953.  
  954.     virtual OSErr InteractWithUser(long timeOutInTicks,
  955.                                    NMRecPtr nmReqPtr, 
  956.                                    AEIdleUPP idleProc);
  957.         // Wrapper for AEInteractWithUser. Virtual bottleneck for the Notification Manager.
  958.         // Don't use this directly -- call MAInteractWithUser instead. 
  959.         
  960.     virtual Boolean ActivateBusyCursor(Boolean entering);
  961.         // Called when the busy cursor mechanism should be activated or deactivated.
  962.  
  963.     virtual Boolean AlertFilter(DialogRef theDialog, EventRecord& theEvent,
  964.                                        short& itemHit);
  965.                                        
  966.     virtual Boolean AppleEventIdleProc(EventRecord& theEventRecord,
  967.                                               long& sleepTime,
  968.                                                RgnHandle& mouseRgn);
  969.         // Called by the default AppleEvent idle proc MacAppAppleEventIdleProc.
  970.         // Provides default idle behavior by handling update and activate events.
  971.         
  972.     virtual Boolean StandardFileFilter(DialogRef theDialog,
  973.                         EventRecord& theEvent, short& itemHit, void* yourDataPtr);
  974.         // Called by the default Standard File filter proc MacAppStandardFileFilterProc.
  975.  
  976.     virtual void DoMakeViewServer();
  977.         // instantiates the global view server
  978.         
  979.     virtual void GetApplicationName(CStr255& theName);
  980.         // The default behavior is to return the name supplied by GetAppParms
  981.  
  982. #if qContainer
  983.     //------------------------------------------------------------------------------------
  984.     // Container Application Support
  985.     //------------------------------------------------------------------------------------
  986.  
  987. public:
  988.  
  989.     virtual    void     AddCADocument(TFileBasedDocument* aNewDocument);
  990.     virtual void     DeleteCADocument(TFileBasedDocument* docToDelete);
  991.  
  992.     static  void    FocusAcquiredProc(CADocumentRef aCADocRef, CAFocusType focusType);
  993.     static  void    FocusLostProc(CADocumentRef aCADocRef, CAFocusType focusType);
  994.     static  void    WindowActivateHandler(WindowPtr    theWindow, Boolean activating);
  995.     static  pascal  Boolean FrameShapeRequestHandler(CADocumentRef aCADocRef,
  996.                                                       CAFrameRef frameRef,
  997.                                                       RgnHandle aRgn);
  998.     static Boolean    AdjustBorderHandler(CADocumentRef aCADocRef,
  999.                                         CAFrameRef frameRef,
  1000.                                         RgnHandle aRgn);
  1001.  
  1002.     TList*             fCADocumentList;                        //list of CADocuments
  1003.  
  1004. protected:
  1005.     CADocumentRef    fCurrentDocument;
  1006.  
  1007.  
  1008. #endif
  1009. };
  1010.  
  1011. //----------------------------------------------------------------------------------------
  1012. // TNewDocumentCommand: Tells the application open a new document.
  1013. //----------------------------------------------------------------------------------------
  1014.  
  1015. //----------------------------------------------------------------------------------------
  1016. // TFilesCommand: Retreives a list of files from an AppleEvent Abstract class for
  1017. // TODocCommand and TPDocCommand.
  1018. //----------------------------------------------------------------------------------------
  1019.  
  1020. //----------------------------------------------------------------------------------------
  1021. // TODocCommand: Accepts a list of file aliases and opens each of them
  1022. //----------------------------------------------------------------------------------------
  1023.  
  1024. //----------------------------------------------------------------------------------------
  1025. // TQuitCommand: Tells the application to do its pre-quitting stuff.
  1026. //----------------------------------------------------------------------------------------
  1027.  
  1028. //----------------------------------------------------------------------------------------
  1029. // TQuitAppCommand: Tells the application to quit in a recordable manner.
  1030. //     Don't issue a TQuitAppCommand to quit the application--issue a
  1031. //     TQuitCommand instead.
  1032. //----------------------------------------------------------------------------------------
  1033.  
  1034. //----------------------------------------------------------------------------------------
  1035. // TAboutBoxCommand: Tells the application to show its about box.
  1036. //----------------------------------------------------------------------------------------
  1037.  
  1038. //----------------------------------------------------------------------------------------
  1039. // TEventRetrieverCommand: Retrieve Events and process them.
  1040. //----------------------------------------------------------------------------------------
  1041.  
  1042. class TEventRetrieverCommand : public TCommand
  1043. {
  1044.     MA_DECLARE_CLASS;
  1045.     
  1046. public:
  1047.     TEventRetrieverCommand();
  1048.         // Empty constructor to satisfy compiler.
  1049.     virtual ~TEventRetrieverCommand();
  1050.         // Destructor
  1051.         
  1052.     void IEventRetrieverCommand(CommandNumber itsCommandNumber);
  1053.         // Initialize the EventCommand procedurally.
  1054.         
  1055.     virtual Boolean NeedsToUnloadAllSegments();
  1056.         // Return false since we don't want to unload the segments for every event
  1057.  
  1058.     virtual void DoIt();
  1059.         // Retrieve and process an event
  1060.  
  1061. };
  1062.  
  1063.  
  1064. //----------------------------------------------------------------------------------------
  1065. // Globals defined by this unit
  1066. //----------------------------------------------------------------------------------------
  1067.  
  1068. extern TDispatcher* gDispatcher;            // the application object
  1069.  
  1070. extern Boolean gInitialized;                // Set to true at top of TDispatcher::Run()
  1071.  
  1072. extern AEAddressDesc gServerAddress;        // Address of the AppleEvent Server. Initialized
  1073.                                             // to send to ourselves.
  1074.                                         
  1075. extern Boolean        gHasODFocus;            //Do we have the standard focus? (We are in control)
  1076. extern Boolean        gHasODModalFocus;        //Do we have the modal focus?                                     
  1077.  
  1078. #endif // __UDISPATCHER__
  1079.